概述

Zapier 是一个用于创建集成和工作流的平台。这个 CLI 是您通往 Zapier 平台创建自定义应用程序的门户。

本文档描述了最新 CLI 版本（17.3.1，截至撰写时）。如果您使用的是旧版本的 CLI，建议查看这些历史版本：

CLI 文档：16.x、15.x
CLI 命令参考：16.x、15.x
模式参考：16.x、15.x

入门指南

要求

开发时您可以使用任意 Node 版本，但最终代码需确保与 v18 兼容。如果您使用尚未在 v18 中可用的功能，可以使用 Babel（或其他类似工具）将代码转译为兼容格式。

为了确保用户稳定性，我们强烈建议您在代码发布给用户之前，在 v18 上运行测试。这可以通过多种方式实现。

首先，使用 CI 工具（如 Travis CI 或 Circle CI，这些工具对开源项目是免费的）。我们在模板集成中提供了一个示例 .travis.yml 文件，以帮助您入门。

或者，您可以使用工具如 nvm 来更改本地 Node 版本。然后，您可以使用 nvm use v18 切换版本，或者运行 nvm exec v18 zapier test，这样您可以在开发时无需切换版本即可运行测试。

快速设置指南

首先，安装 CLI 并设置身份验证，以创建一个可工作的“Zapier 示例”集成。它将对您私有，并在您的实时 Zap 编辑器中可见。

# 全局安装 CLI
npm install -g zapier-platform-cli

# 使用部署密钥设置对 Zapier 平台的身份验证
zapier login

此时，您的 Zapier CLI 应该已安装并准备就绪。接下来，我们将创建您的第一个集成！

# 创建一个包含最小必需文件的目录
zapier init example-app

# 进入新目录
cd example-app

# 安装集成所需的所有库
npm install

根据集成的身份验证方法，您可能还需要将 CLIENT_ID 和 CLIENT_SECRET 设置为环境变量。这些是 OAuth1 术语中的消费者密钥和机密。

# 在 Zapier.com 上设置环境变量
zapier env:set 1.0.0 CLIENT_ID=1234
zapier env:set 1.0.0 CLIENT_SECRET=abcd

现在，您应该有一个可工作的本地集成。您可以运行几个本地命令来测试它。

# 运行本地测试
# 这与 npm test 类似，但会添加一些额外的环境变量
zapier test

接下来，您可能希望将集成上传到 Zapier，以便开始进行实时测试。

# 将您的集成推送到 Zapier
zapier push

创建本地集成

集成可以完全在本地创建，它们是简单的 Node.js 应用程序，使用标准 Node 环境，并且应该完全可测试。但是，本地集成在您运行 zapier register 之前会保持本地状态。

# 创建文件夹
mkdir zapier-example
cd zapier-example

# 从模板创建所需的文件
zapier init . --template minimal

# 安装集成所需的所有库
npm install

如果您想管理您的本地集成，请使用这些命令：

zapier init myapp - 初始化/启动本地集成项目
zapier convert 1234 . - 从现有集成初始化/启动
zapier scaffold resource Contact - 自动注入新的资源、触发器等
zapier test - 运行与 npm test 相同的测试
zapier validate - 确保您的集成有效
zapier describe - 打印关于您的集成的有用信息

本地项目结构

在集成的文件夹中，您应该看到以下推荐结构。index.js 是 Zapier 进入您的集成的入口点。Zapier 期望您在那里导出 App 定义。

$ tree .
.
├── README.md
├── index.js
├── package.json
├── triggers
│   └── contact-by-tag.js
├── resources
│   └── Contact.js
├── test
│   ├── basic.js
│   ├── triggers.js
│   └── resources.js
├── build
│   └── build.zip
└── node_modules
    ├── ...
    └── ...

本地 App 定义

您的 App 的核心定义如下，这是 index.js 应该提供的唯一导出：

const App = {
  // 两个版本字符串都是必需的
  version: require("./package.json").version,
  platformVersion: require("zapier-platform-core").version,

  // 查看“身份验证”部分
  authentication: {},

  // 查看“反序列化”部分
  hydrators: {},

  // 查看“进行 HTTP 请求”部分
  requestTemplate: {},
  beforeRequest: [],
  afterResponse: [],

  // 查看“资源”部分
  resources: {},

  // 查看“触发器/搜索/创建”部分
  triggers: {},
  searches: {},
  creates: {},
};

module.exports = App;

Zapier 平台模式

Zapier 平台模式提供了 Zapier 集成的各种模式组件的详细信息。每种模式概述了所需字段、数据类型以及身份验证、触发器、创建、搜索和 HTTP 请求等功能的配置。对于集成开发人员来说，参考此模式文档至关重要，因为它确保遵循正确的结构并使用必要的组件。详细的示例、有效配置和反示例有助于指导集成开发人员创建可靠且功能齐全的集成，避免常见错误，并确保与 Zapier 平台兼容。

注册集成

在 Zapier 中注册您的集成是必要的第一步，它仅启用基本的管理功能，但这是后续操作的基础。它应在 zapier push 之前发生，后者用于在 Zapier 接口和编辑器中实际暴露集成版本。

# 注册您的集成
zapier register "Zapier 示例"

# 列出您的集成
zapier integrations

如果您想管理您的集成，请使用这些命令：

zapier integrations - 列出您可以管理的 Zapier 集成
zapier register "集成标题" - 在 Zapier 中创建新集成
zapier link - 列出并将选定的 Zapier 集成链接到当前文件夹
zapier history - 打印集成的历史记录
zapier team:add user@example.com admin - 添加管理员以帮助维护/开发您的集成
zapier users:add user@example.com 1.0.0 - 邀请用户试用集成版本 1.0.0

（由于原文较长，以上为完整翻译。如果需要进一步调整，请提供反馈。）

入门指南​

要求​

快速设置指南​

创建本地集成​

本地项目结构​

本地 App 定义​

Zapier 平台模式​